<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">

<!--
 Copyright (C) 2007 Sun Microsystems, Inc. All rights reserved. Use is
 subject to license terms.
-->

<html>
    <head>
        <title></title>
    </head>
    <body>
        <p>
            Provides support for defining properties and creating bindings between
            sets of two properties.
        </p>
        <h3>Properties</h3>
        <p>
            A property is defined by creating an instance of a concrete implementation
            of the {@link org.jdesktop.beansbinding.Property} class. This package
            provides two concrete {@code Property} implementations of interest:
            {@link org.jdesktop.beansbinding.BeanProperty} allows Java Bean properties
            to be addressed by providing their path as a String.
            {@link org.jdesktop.beansbinding.ELProperty} allows Java Bean properties
            to be addressed similarly and then be used in various ways in an EL expression.
            A simple {@code BeanProperty} that refers to a "firstName" Java Bean property,
            might look like:
        </p>
        <pre><code>
    BeanProperty firstNameP = BeanProperty.create("firstName");
        </code></pre>
        <p>
            An {@code ELProperty} to combine the "firstName" and "lastName"
            properties of a Java Bean into a full name, might look like:
        </p>
        <pre><code>
    ELProperty fullNameP = ELProperty.create("${firstName} ${lastName}");
        </code></pre>
        <p>
            These property objects can then be used to operate on a Java Bean having
            the properties of interest. For example:
        </p>
        <pre><code>
    // prints the first name on the person object
    System.out.println(firstNameP.getValue(person));

    // prints the full name of the person object
    System.out.println(fullNameP.getValue(person));

    // sets the first name of the person object to "Duke"
    firstNameP.setValue(person, "Duke");

    // listen for changes to the person's full name
    fullNameP.addPropertyStateListener(person, listener);
        </code></pre>
        <p>
            Both of these property implementations are designed to work with bean
            properties that follow the Java Beans specification. Sometimes, however,
            a property of interest on a bean outside of your control may not be exposed
            in the correct way, and you want to adapt it for use in binding.
            Other times you may want to extend the set of properties that a bean
            exposes, simply for use in binding. These cases are provided for by
            the <a href="ext/package-summary.html">org.jdesktop.beansbinding.ext</a>
            package.
        </p>
        <h3>Bindings</h3>
        <p>
            A binding is created between two {@code Property} instances, and the objects
            on which the {@code Property} objects should operate, by creating an instance
            of a concrete implementation of the {@code Binding} class. Once the binding is
            realized, by a call to the {@code bind} method, a {@code Binding} starts
            tracking changes to the properties on both ends, and a typical {@code Binding}
            implementation will sync the properties with each other based on on some defined
            strategy.
        </p>
            This package provides one concrete subclass of {@code Binding} called
            {@link org.jdesktop.beansbinding.AutoBinding} which syncs the properties based
            on a configurable update strategy. {@code AutoBindings} are created by
            calling one of the static {@code createAutoBinding} methods in the
            {@link org.jdesktop.beansbinding.Bindings} class. For example:
        </p>
        <pre><code>
    BeanProperty firstNameP = BeanProperty.create("firstName");
    BeanProperty textP = BeanProperty.create("text");
    Binding binding = Bindings.createAutoBinding(READ_WRITE, person, firstNameP, jTextField, textP);
    binding.bind();
        </code></pre>
        <p>
            Before a value from a source property is set on a target property, it passes
            through an optional {@link org.jdesktop.beansbinding.Converter} to convert
            it between the source type and target type. Before a value passed from a
            target property back to a source property, it passes first through the
            optional {@code Converter} and then through an optional
            {@link org.jdesktop.beansbinding.Validator}, which can reject invalid values.
        </p>
    </body>
</html>
